home *** CD-ROM | disk | FTP | other *** search
/ Experimental BBS Explossion 3 / Experimental BBS Explossion III.iso / c / pcw.zip / PCW.DOC < prev    next >
Text File  |  1991-12-29  |  81KB  |  2,086 lines
  1. ----L----l----+----2----+----3----+----4----+----5----+----6----+----j----J----8
  2.     
  3.  
  4.  
  5.                               PC Windows Phase I
  6.                            Copyright (c) 1989, 1990
  7.                                 By Stan Milam
  8.  
  9.  
  10.                                  Introduction
  11.  
  12.          PC windows, called PCW, is a library of C and assembler routines 
  13.     designed  to give you control over the video of your computer.    PCW 
  14.     has  been  written to work with the IBM family of personal  computers 
  15.     and 100%  compatibles using Microsoft C version 5.0,  Turbo C version 
  16.     1.5 and up, and Mix Software's Power C version 1.1.6 and up.   PCW is 
  17.     a  powerful  tool designed to give you,  the C programmer,   complete 
  18.     power  over  the video hardware of your PC.   PCW features  automatic 
  19.     detection of the video hardware, windows,  quick direct memory screen 
  20.     writes,  video BIOS support, MOUSE support, keyboard support,  pop-up 
  21.     menus  (using the Mouse),  and a Lotus style menu with a twist.  
  22.  
  23.  
  24.          There is nothing fancy about the format of this document.   What 
  25.     I  will  tell  you  here  will concern  PCW  global  variables,   PCW 
  26.     functions, and PCW manifest constants. Global variables are few - the 
  27.     fewer  the better.   All functions will include a description of  use 
  28.     and an example program.   Manifest constants will have to live  with 
  29.     just a description. 
  30.     
  31.  
  32.                     Compiling and Linking with PC Windows
  33.  
  34.     How  you  compile and link with PCW depends on the compiler  you  are 
  35.     using  and  how  you  have set up your computer system  and  the  DOS 
  36.     environment  variables  used  by  your compiler.    We  will  examine 
  37.     compiling  and linking with Power C,  Microsoft C,  and Turbo C  with 
  38.     both the command line version and the Integrated Environment version. 
  39.  
  40.                                The Header Files
  41.  
  42.     In  all  cases you should copy the PC Windows header files  into  the 
  43.     include directory used by your compiler.  The include directory  will 
  44.     be different for each compiler.  If you have any doubts where or what 
  45.     your  include  directory is refer to your compiler  manual.    Listed 
  46.     below  are the normal location and name of the include directory  for 
  47.     each compiler: 
  48.  
  49.     c:\powerc                               /* Or whatever */
  50.     c:\include                              /* Microsoft C */
  51.     c:\turboc\include                       /* Turbo C */
  52.  
  53.     Now perform the following copy operations:
  54.  
  55.     copy *.h  [to one of the directories listed above]
  56.     copy *.i  [to one of the directories listed above]
  57.  
  58.                                 The Libraries
  59.  
  60.     There   should  be  three  files with  the  .LIB  extension  on   the 
  61.     distribution  diskette.   These .LIB files match to the compilers  as 
  62.     follows: 
  63.  
  64.     mspcwmm.lib - Microsoft C V5.0 and up and Quick C.
  65.     tcpcwmm.lib - Turbo C 
  66.     pcpcwmm.lib - Power C
  67.     ztpcwmm.lib - Zortech C V2.1
  68.  
  69.     These  are  medium  model  libraries and need to  be  copied  to  the 
  70.     directory  that  you  have  set up for use by  the  linker  for  your 
  71.     libraries.  Here are some examples of what we mean:
  72.  
  73.     copy tc*.lib c:\turboc\lib     /* Turbo C */
  74.     copy ms*.lib c:\lib            /* Microsoft */
  75.     copy pc*.lib c:\powerc         /* Power C */
  76.     copy zt*.lib c:\zt\lib         /* Zortech */
  77.  
  78.  
  79.  
  80.                                    Power C
  81.  
  82.     Here  we  examine how you might compile using the Power  C  compiler.  
  83.     First  lets assume you have all of your Power C executables,   header 
  84.     files,  and libraries in a directory on C: drive called POWERC.   The 
  85.     c:\powerc   directory  will  need  to be included  in  the  DOS  PATH 
  86.     statement.  You  may set the DOS PATH in the AUTOEXEC.BAT file  which 
  87.     is  executed when the computer boots up as follows: 
  88.  
  89.     set path=c:\dos;c:\powerc;
  90.  
  91.     This  will  ensure that DOS finds the Power C  executables  when  you 
  92.     invoke them.   However,  before you can compile you must set some DOS 
  93.     environment  variables that will be used by the compiler to  identify 
  94.     what  directories you have placed header files and  libraries.    The 
  95.     environment variables are LIBRARY,  PCOPTIONS,  LIBNAMES.    LIBNAMES 
  96.     only  pertains if you are using Power C version 1.2  or later.    The 
  97.     LIBRARY variable will tell the Power C linker what directory you have 
  98.     placed the standard linkage libraries, while PCOPTIONS can be used to 
  99.     point  the  compiler to a directory where header files can be  found, 
  100.     and  LIBNAMES   will   be  used  to point the Power   C   linker   to  
  101.     external  libraries like PC Windows.    Again,   you must  set  these 
  102.     variables  in the AUTOEXEC.BAT using the DOS SET command.    Assuming 
  103.     we  wanted to do all  of  our  work out of the C:\POWERC directory we  
  104.     would  set  our environment variables as follows: 
  105.  
  106.     SET PCOPTIONS=/IC:\POWERC
  107.     SET LIBRARY=C:\POWERC
  108.     SET LIBNAMES=C:\POWERC\PCPCWMM.LIB   /* version 1.2 and up only */
  109.  
  110.     If  you are using a version of Power C earlier than version 1.2   you 
  111.     will not be able to use the LIBNAMES variable,  although it does  not 
  112.     hurt to add it in case you plan to upgrade.   If you can not use  the 
  113.     LIBNAMES  variable  you must use the following command line  to  link 
  114.     your program to the PC Windows library: 
  115.  
  116.     pcl myprog;c:\powerc\pcpcwmm.lib
  117.  
  118.     You  must  do  this every time you link (its enough to make you  want  
  119.     to upgrade!).
  120.     
  121.                                    Turbo C
  122.  
  123.     Okay,   so you don't want to mess around with Power C --  you want to 
  124.     use Turbo C.   First you will need to make sure the Turbo C directory 
  125.     is  in the DOS PATH.   What happens next depends on which version  of 
  126.     the   compiler  you  are going to use.    If you are a very   serious  
  127.     programmer  you will probably use the command line version (TCC)  and 
  128.     if  you are a casual or beginning C programmer you will probably  use 
  129.     the Integrated Environment (TC).  We will cover both, but separately. 
  130.     First  if  you  are using the command line version you will  need  to 
  131.     check  the  contents of a file called TURBOC.CFG.   This file  points 
  132.     Turbo  C  (TCC)   to  the directories where your  include  files  and 
  133.     libraries are.  They might look something like this: 
  134.  
  135.     -IC:\TURBOC\INCLUDE
  136.     -LC:\TURBOC\LIB
  137.  
  138.     The  TURBOC.CFG  file contains information that you  would  like  the 
  139.     compiler to use every time you compile.   For example,  if you always 
  140.     wanted  type char to default to unsigned every time you compiled  you 
  141.     would add the -K option to the TURBOC.CFG file.   As it is, it should 
  142.     always  contain  the  PATH to the include directory and  the  library 
  143.     directory.   Now,  you should copy the PC Windows Libraries for Turbo 
  144.     C to the C:\TURBOC\LIB directory (above). 
  145.     
  146.     copy tcpcw*.lib c:\turboc\lib
  147.  
  148.     The  command line compiler can not only compile your program  it  can 
  149.     link it too.  For example:
  150.  
  151.     tcc -mm  -K menudemo pdemo ldemo tcpcwmm.lib
  152.  
  153.     The  above example would compile the Menu Demo program in the  medium 
  154.     memory model and link it with the PC Windows library, TCPCWMM.LIB. 
  155.     
  156.     
  157.     Turbo C Integrated Environment:
  158.  
  159.     If you are using the Integrated Environment to edit,  compile,  link, 
  160.     and run your program you will need to do a couple of extra things  to 
  161.     make a program work with PC Windows.   First you will need to set the 
  162.     memory  model  you  wish  to compile with to  medium  using  the  key 
  163.     commands  ALT O/C/M  (We use medium memory model in these  directions 
  164.     because it is the only library we ship on the distribution diskette). 
  165.     Next  you  need  to be sure the Integrated Environment is  using  the 
  166.     correct  directories.    Use the key commands ALT O/D to get  to  the 
  167.     directories window and make sure the INCLUDE DIRECTORIES:  is set  to 
  168.     C:\TURBOC\INCLUDE,    and   the  LIBRARY  DIRECTORY:    is   set   to 
  169.     C:\TURBOC\LIB.  Now, you are almost ready to run with PC Windows, but 
  170.     first  we need a way to tell the Integrated Environment that we  will 
  171.     need to link to a user library.   To do this we use Turbo C's Project 
  172.     Manager.   It is very simple to do:   first you create and edit a new 
  173.     file  in  which you place  all  the names of your source modules  and 
  174.     include the name  of the PC Windows library, TCPCWMM.LIB, and finally 
  175.     save  the  file  with  the  name of your main  program  with  a  .PRJ 
  176.     extension.    Next  use  the  key commands ALT  /P/P  to  notify  the 
  177.     Integrated  Environment of your project name.   Now you are ready  to 
  178.     run.    For  example to run the example program MENUDEMO out  of  the 
  179.     Integrated  Environment  you  would  create  a  project  file  called 
  180.     MENUDEMO.PRJ with these contents: 
  181.  
  182.     MENUDEMO.C
  183.     PDEMO.C
  184.     LDEMO.C
  185.     TCPCWMM.LIB
  186.  
  187.     Next  you would set the PROJECT FILE to MENUDEMO.PRJ.  Now you  would 
  188.     edit  MENUDEMO.C  and run or compile as a normal program and Turbo  C 
  189.     would  know  to  compile  the three C  source  files  and  link  with 
  190.     TCPCWMM.LIB. 
  191.     
  192.  
  193.  
  194.                                Microsoft C V5.1
  195.  
  196.     Okay,  now you've hit the big time and are using Microsoft C V5.0  or 
  197.     greater.    To  use PC Windows with MSC you must be sure  the  header 
  198.     files  are  copied to the INCLUDE directory and the  PCW  library  is 
  199.     copied to the LIB directory.  
  200.  
  201.     copy *.h c:\include
  202.     copy *.i c:\include
  203.     copy mspcw*.lib c:\lib
  204.  
  205.     Now you are ready to write and compile programs using PC Windows.  To 
  206.     compile  and  link  with  PC Windows in one  step  you  may  use  the 
  207.     following command line as a model: 
  208.  
  209.     cl -AM yourpgm.c /link mspcwam.lib        /* OR..... */
  210.     cl -AM yourpgm.c mspcwam.lib
  211.  
  212.     For example to compile and link the MENUDEMO program you would supply 
  213.     the following command line:
  214.  
  215.     cl -AM menudemo.c pdemo.c ldemo.c /link mspcwam
  216.  
  217.     NOTE:   If your are using Microsoft's Quick C version 2.0 you may use 
  218.     the  exact  same command lines shown above to compile and  link  your 
  219.     programs  with one exception:   change cl to qcl.   If you are  using 
  220.     version  1.x  of  Quick C you may still compile  and  link  with  the 
  221.     MSPCWAM  library,   but the command line options will  be  different.  
  222.     Please refer to your Quick C manual for details,  and please consider 
  223.     an upgrade to version 2.0.
  224.     
  225.  
  226.     Quick C Version 2.0 Integrated Environment:
  227.  
  228.     Here  we  discuss using the integrated environment using  Microsoft's 
  229.     Quick  C  version 2.0.   Note you can use version 1.x of Quick C  but 
  230.     there  are  very big differences between the two versions.   We  only 
  231.     discuss  version 2.0,  but the idea is the same.   If you  are  using 
  232.     version 1.x of Quick C refer to MULTIPLE-MODULE PROGRAMS in chapter 6 
  233.     of your Quick C manual. To compile and link with PC Windows and Quick 
  234.     C's integrated environment you will have to set up a program list for 
  235.     every program you run.  Do not despair as this is a simple operation.  
  236.     Futhermore,  you will need to set your memory model to medium.   From 
  237.     Quick  C's menu you will need to select the MAKE option (ALT M)   and 
  238.     then  select  the (S)et Program List option.    Quick C will show you 
  239.     a  list   of  available  program lists already saved on  disk.     If  
  240.     your  program is contained in one of these lists then select  it  and 
  241.     continue on  your  merry way.   However,   if this is the first  time  
  242.     you   are  compiling   your  program you will need to  create  a  new 
  243.     program   list.   In the program list you will need to include  every 
  244.     source  code member needed  and one of these members will need to  be 
  245.     MSPCWAM.LIB.      This will notify Quick C that your program needs to 
  246.     be  linked with the  PC Windows library.   For example,  to  compile, 
  247.     link,   and run the menudemo program  from the Integrated Environment 
  248.     you would build a list  with the following members: 
  249.  
  250.        menudemo.c
  251.        ldemo.c
  252.        pdemo.c
  253.        mspcwam.lib
  254.  
  255.     Once you have built this list you will need to save it.   Once  saved 
  256.     you  are ready to compile (provided you have set your memory model to 
  257.     medium). 
  258.  
  259.     For information concerning program lists refer to the section labeled 
  260.     Creating a Program List in your UP AND RUNNING manual.
  261.     
  262.  
  263.                               The Function Classes
  264.  
  265.          The  functions in PCW can be divided into classes.   First  come 
  266.     the "Quick"  screen write functions.   These functions all start with 
  267.     the letter "q".   These functions do as their name implies - write to 
  268.     the screen very, very, very quickly.  There is no character filtering 
  269.     with  these  functions.    This means if you send the  string  "Hello 
  270.     World\n"  to  the screen the '\n'   newline character  would  not  be 
  271.     filtered  and  would  appear as a funny little glitch on  your  video 
  272.     screen.   Next would come the window functions.    All of the  window 
  273.     functions, with the exception of wexplode, wpush, and wframe, require 
  274.     a window handle as an argument.  A window handle is obtained by using 
  275.     one of the above functions.    PCW supports overlapping windows,  and 
  276.     any  window  that has been established can be addressed at any  time, 
  277.     even if the windows are overlapped.  PCW will make the window that is 
  278.     addressed  the  "active"   window.    This means  if  the  window  is 
  279.     overlapped and addressed with any window function,  that window  will 
  280.     be  "floated"   to  the top and made to be the active  window.    For 
  281.     example,   you are using three windows concurrently on the screen and 
  282.     your window handles are wnd1, wnd2, and wnd3.  The third window would 
  283.     be the active window.  Now suppose they overlapped as shown: 
  284.  
  285.                           +---------------+
  286.                           |     wnd1      |    
  287.                           |               |
  288.                           |     +----------------+
  289.                           |     |      wnd2      |
  290.                           |     |                |
  291.                           |     |        +------------+
  292.                           |     |        |    wnd3    |
  293.                           |     |        |            |
  294.                           |     |        +------------+
  295.                           +-----|                |
  296.                                 +----------------+
  297.    
  298.     Now suppose you addressed wnd2  with a window function.   The windows 
  299.     would be reordered as follows: 
  300.  
  301.                           +---------------+
  302.                           |      wnd1     |
  303.                           |      +----------------+
  304.                           |      |      wnd2      |
  305.                           |      |                |
  306.                           |      |                |----+
  307.                           |      |                |3   |
  308.                           |      |                |    |
  309.                           |      |                |----+
  310.                           +------|                |
  311.                                  +----------------+
  312.  
  313.     Notice that wnd2 now covers wnd3 as well as wnd1.  The only time this 
  314.     will  not work is when a window is hidden.   If it is hidden the  the 
  315.     window function is ignored.   It is wise to keep your windows  simple 
  316.     and  try to avoid overlaps to keep them from thrashing around on  the 
  317.     screen and wasting time. 
  318.  
  319.     Another  class  of  functions would be the Mouse  functions.   These 
  320.     functions implement usage of a Microsoft compatible Mouse.  Other 
  321.     function classes would be,  Keyboard, BIOS dependant,  Miscellaneous, 
  322.     and PCW Environment functions.
  323.     
  324.  
  325.                                Global Variables
  326.  
  327.     A  few  words  about global variables declared and maintained  by  PC 
  328.     Windows  is  in  order.    The keywords here are  "maintained  by  PC 
  329.     Windows".    What this means is you should let PC Windows worry about 
  330.     what  values  are stored in them.   You may inquire as to what  their 
  331.     values are, but NEVER, NEVER, NEVER change the values in your program 
  332.     or  it is guaranteed PC Windows will not work properly.   The  global 
  333.     variables are declared in the PCWPROTO.H header file.  Following is a 
  334.     description of each variable and the usage of each. 
  335.  
  336.                                    _adaptor
  337.  
  338.     Description:   The _adaptor global variable is set by the PCW startup 
  339.     code to a value that indicates what video adaptor is used on the host 
  340.     system.   The manifest constants MDA,  CGA,  EGA,  VGA can be used by 
  341.     your  program  to query the value in the  _adaptor  variable.     For 
  342.     example,  if (_adaptor > CGA), could be used to determine if your are 
  343.     dealing with an EGA or VGA adapter. 
  344.  
  345.                                    _monitor
  346.  
  347.     Description:   The _monitor global variable is set by the PCW startup 
  348.     code  to  a  value that indicates whether the monitor is a  color  or 
  349.     monochrome  monitor.    The manifest constants MONO and COLOR can  be 
  350.     used to determine the value of the _monitor variable. 
  351.  
  352.                                   _video_ram
  353.  
  354.     Description:  The _video_ram global variable is set by the PCW 
  355.     startup  code  to  a value that indicates the amount of RAM  that  is 
  356.     allocated by the host video system for use by the video system.   The 
  357.     value in this variable is expressed in K bytes. 
  358.  
  359.                                    mpresent
  360.  
  361.     Description:    The  mpresent  variable is set  by  the  init_mouse() 
  362.     function  when it is determined whether there is a mouse attached  to 
  363.     the  host system.    This is a neccessary and useful variable in that  
  364.     the Mouse   software  is independent of PC Windows and it is  helpful  
  365.     to  know   if the Mouse is home or not.     For example,     if  your  
  366.     program  uses  the  Mouse you will want to check to see if the  Mouse  
  367.     is  home before using any PCW function.  Example: 
  368.  
  369.         if (mpresent) hide_mouse();        /* if Mouse home hide it */
  370.         wnd = wpop(wnd);                   /* Remove the window */
  371.         if (mpresent) show_mouse();        /* Reshow the Mouse if home */
  372.  
  373.                                     Vbump
  374.  
  375.     Description:    The  Vbump variable is set by PCW at startup  and  is 
  376.     updated   continually  by  PCW every time one of  PCW's  functions is 
  377.     called.   It is used internally by PCW in the calculation of  offsets 
  378.     into video memory. 
  379.  
  380.                                   CheckSnow
  381.  
  382.     Description:   The CheckSnow variable is set by PCW at startup and is 
  383.     used by PC Windows'  assembly modules whether to execute the code  to 
  384.     reduce the snow that appears when using a CGA adapter. 
  385.     
  386.                                Window Functions
  387.  
  388.  
  389.                                    wframe()
  390.  
  391.     #include <pcwproto.h>
  392.     WNDPTR *wframe(int ur,int uc,int lr, int lc,int fcolr,int bcolr);
  393.  
  394.     Description:    The  wframe()  function will frame a  window  at  the 
  395.     specified coordinates.  Ur,  uc,  lr,  and lc are the upper and lower 
  396.     rows and columns of the window.   Fcolr and bcolr are the  foreground 
  397.     and  background colors of the window.   The window is added  into  an 
  398.     internal  list  of  windows.   The type of frame and  its  color  are 
  399.     determined by the functions setborder() and bordercolor respectively. 
  400.  
  401.     Returns:  A pointer to type WNDPTR, which will be used as a handle to 
  402.     the  window on all subsequent window operations.   If wframe()  could 
  403.     not create the window for any reason a NULL pointer will be returned. 
  404.  
  405.     Example:
  406.  
  407.     #include <stdio.h>
  408.     #include <pcwproto.h>
  409.  
  410.     void main(void) {
  411.       WNDPTR *wnd;
  412.       
  413.       setborder(DOUBLEALL);
  414.       bordercolor(WHITE,BLUE);
  415.       wnd = wframe(6,20,18,60,BLUE,LIGHTGRAY);
  416.       if (!wnd)  exit(3);
  417.       swait(5);
  418.       wnd = wpop(wnd);
  419.     }
  420.     
  421.      
  422.                                   wexplode()
  423.     
  424.     #include <pcwproto.h>
  425.     WNDPTR *wexplode(int ur,int uc,int lr,int lc,int fcolor,int bcolor);
  426.     
  427.     Description:   The wexplode()  function is very similar to the wframe 
  428.     function.    It also frames a window at the specified coordinates and 
  429.     returns a window handle.   The only difference is the window explodes 
  430.     from  a  central  point specified by the  coordinates  quickly,   and 
  431.     smoothly.  The border type and color is determined by the values last 
  432.     passed to the setborder() and bordercolor() functions respectively. 
  433.  
  434.     Returns:   A  pointer of type WNDPTR,  which will be used as a window 
  435.     handle on all subsequent window functions that affect the window. 
  436.  
  437.     Example:
  438.  
  439.     #include <stdio.h>
  440.     #include <pcwproto.h>
  441.  
  442.     void main(void) {
  443.       WNDPTR *wnd;
  444.       
  445.       setborder(DOUBLEALL);
  446.       bordercolor(WHITE,BLUE);
  447.       wnd = wexplode(6,20,18,60,BLUE,LIGHTGRAY);
  448.       if (!wnd)  exit(3);
  449.       swait(5);
  450.       wnd = wpop(wnd);
  451.     }
  452.     
  453.  
  454.                                     wpush()
  455.  
  456.     #include <pcwproto.h>
  457.     WNDPTR *wpush(int urow, int ucol, int lrow, int lcol);
  458.  
  459.     Description:    The  wpush()  function will save the contents of  the 
  460.     screen  specified by the coordinates.   The contents of the  "window" 
  461.     can be restored at a later time.   The "pushed"  area is treated just 
  462.     like any other window by the window routines. 
  463.  
  464.     Returns:   A pointer to type WNDPTR, which can be used as a handle to 
  465.     the  window in subsequent window operations.   Returns a NULL pointer 
  466.     if the operation failed for any reason. 
  467.  
  468.     Example:
  469.  
  470.     #include <stdio.h>
  471.     #include <pcwproto.h>
  472.  
  473.     void main(void) {
  474.        WNDPTR *savewnd;
  475.        int mxr, mxc;
  476.  
  477.        if (!get_video_state(&mxr,&mxc)) exit(3);
  478.        savewnd = wpush(1,1,mxr,mxc); vcls();
  479.        qfill(6,20,18,60,RED,RED,32);
  480.        swait(5); savewnd = wpop(savewnd);
  481.     }
  482.     
  483.     
  484.                                    wprintf()
  485.        
  486.     #include <pcwproto.h>
  487.     int wprintf(WNDPTR *wnd, int row, int col, char *format,...);
  488.  
  489.     Description:  The wprintf() function  writes formatted output strings 
  490.     to  a specified  window similar to the standard printf()    function.    
  491.     The  WNDPTR   pointer  is  a handle to the window.   The  row  &  col  
  492.     variables  specify  the row and column IN THE WINDOW that you wish to 
  493.     place  the  output,  and the format string is used just as  a  format 
  494.     string  in printf().  The  color of the output is determined  by  the 
  495.     color  attributes  used when framing or exploding  the  window.   The  
  496.     color attributes can be changed by using the set_wnd_attr() function. 
  497.  
  498.     Returns:  A  non-zero value is returned if the function was completed 
  499.     successfully  and  a zero value will be returned for any  reason  the 
  500.     function could not perform its operation. 
  501.  
  502.     Example:
  503.     
  504.     #include <stdio.h>
  505.     #include <pcwproto.h>
  506.  
  507.     void main(void) {
  508.  
  509.        static char format[] = "This is a format string.  Line = %d";
  510.        WNDPTR *wnd;
  511.        int    lcv;
  512.  
  513.        pcwinit(AUTOEXIT);
  514.        wnd = wframe(6,10,18,70,RED,LIGHTGRAY);
  515.        if (!wnd) exit(3);
  516.        for (lcv = 1; lcv < 10; lcv++)
  517.            wprintf(wnd,lcv,CENTER,format,lcv);
  518.        swait(5); wnd = wpop(wnd); 
  519.     }
  520.     
  521.     
  522.                                    wputs()
  523.  
  524.     #include <pcwproto.h>
  525.     int wputs(WNDPTR *wnd, int row, int col, char str[]);
  526.  
  527.     Description:    Wputs()   writes  a  string of  characters  into  the 
  528.     specified window at the specified row and column in the window.   The 
  529.     WNDPTR pointer is a handle to the specified window.   The row and col 
  530.     variables  are the specified row and column INSIDE THE WINDOW.    The 
  531.     character string str[] is the string to be written in the window.  If 
  532.     the string is too long to be displayed entirely in the window then it 
  533.     is  truncated.    The  color  of the characters  in  the  window  are 
  534.     determined  by the colors specified when the window was created  with 
  535.     wframe, wexplode, or wpush.  If the window was created with wpush the 
  536.     default  colors of LIGHTGRAY on BLACK  are used.   If the  window  is 
  537.     overlapped by any other window then the window will be "floated"   to 
  538.     the  top and made the top window.   If row and column are outside  of 
  539.     the  window  boundaries  the string will not be printed  and  a  zero  
  540.     value will be returned. 
  541.  
  542.     Returns:  Non-zero if completed successfully.
  543.  
  544.     Example:
  545.  
  546.     #include <stdio.h>
  547.     #include <pcwproto.h>
  548.  
  549.     void main(void) {
  550.  
  551.        static char hello[] = "Hello World!! PC Windows Here!";
  552.        WNDPTR wnd;
  553.  
  554.        pcwinit(NOEXIT);
  555.        wnd = wexplode(6,10,18,70,BLUE,LIGHTGRAY);
  556.        wputs(wnd,5,CENTER,hello);
  557.        swait(5); wnd = wpop(wnd);
  558.     }
  559.     
  560.  
  561.                                    wtitle()
  562.  
  563.     #include <pcwproto.h>
  564.     int wtitle(WNDPTR wnd,int top_bottom,int mid_left_right,char *title);
  565.  
  566.     Description:     The  wtitle()  function  will  title a  window  that  
  567.     has  been previously  established.  The WNDPTR pointer is a handle to  
  568.     the  window   to be titled.    The  top_bottom parameter is  used  to  
  569.     specify whether the title is to be placed at the top or bottom of the 
  570.     window.    Use  the manifest constants TOP or BOTTOM to  specify  the 
  571.     value.     The mid_left_rite  parameter  specifies whether the  title 
  572.     will be at  the left,    or  in the middle,   or at the right of  the 
  573.     window.     Use   the manifest constants LEFT,   RITE,     MIDDLE  to 
  574.     specify  this value.    The color of the title is specified by  using 
  575.     the  titlecolor()    function.  If   the window is overlapped by  any 
  576.     other  window  it will be promoted to the top and be made the  active 
  577.     window. 
  578.  
  579.     Return:  A non-zero value if successful.
  580.  
  581.     Example:
  582.  
  583.     #include <stdio.h>
  584.     #include <pcwproto.h>
  585.  
  586.     void main(void) {
  587.  
  588.        WNDPTR *wnd;
  589.                
  590.        bordercolor(BLUE,LIGHTGRAY);
  591.        titlecolor(RED,LIGHTGRAY);
  592.        setborder(SINGLESIDES);
  593.        wnd = wframe(6,10,18,70,BLACK,LIGHTGRAY);
  594.        wtitle(wnd,TOP,LEFT," Top Left ");
  595.        wtitle(wnd,TOP,MIDDLE, " Top Middle ");
  596.        wtitle(wnd,TOP,RITE, " Top Right ");
  597.        wtitle(wnd,BOTTOM,MIDDLE," Bottom Middle ");
  598.        swait(5);  wnd = wpop(wnd);
  599.     }
  600.     
  601.     
  602.                                    whide()
  603.  
  604.     #include "pcpwproto.h"
  605.     int whide(WNDPTR *wnd);
  606.  
  607.     Description:    The whide()  function will hide the window  specified 
  608.     with  the  WNDPTR pointer-handle.   When the window is hidden  it  is 
  609.     removed from  the screen and all subsequent addresses to  the  window  
  610.     are ignored.  However,  the window can be moved.    The window can be 
  611.     made visible again by using the wshow() function. 
  612.  
  613.     Returns:  Non-zero value if successful.
  614.  
  615.     Example
  616.  
  617.     #include <stdio.h>
  618.     #include <pcwproto.h>
  619.  
  620.     void main(void) {
  621.  
  622.        WNDPTR *wnd;
  623.  
  624.        wnd = wframe(6,10,18,70,LIGHTGRAY,RED);
  625.        if (wnd == NULL)  exit(3);
  626.        swait(5);  whide(wnd); swait(3);
  627.        wndmove(wnd, 10,20); wshow(wnd);
  628.        swait(5); wnd = wpop(wnd);
  629.     }
  630.     
  631.  
  632.                                    wshow()
  633.  
  634.     #include <pcwproto.h>
  635.     int wshow(WNDPTR *wnd) {
  636.  
  637.     Description:   The wshow()  function will re-show a window that  was 
  638.     previously  hidden  with  the whide function.   The  WNDPTR  pointer 
  639.     variable is a handle to the window to be re-shown. 
  640.  
  641.     Returns:  A non-zero value if the function was successful.
  642.  
  643.     Example:  See previous example for whide() function.
  644.     
  645.  
  646.                                   wndmove()
  647.  
  648.     #include <pcwproto.h>
  649.     int wndmove(WNDPTR *wnd, int row, int col);
  650.  
  651.     Description:   The wndmove()  function will move the window specified 
  652.     with the WNDPTR pointer variable to the specified coordinates,  row & 
  653.     col.    The  variables row and col are coordinates  on  the  physical 
  654.     screen  and  mark where the upper left corner of the window will  be.  
  655.     The  wndmove()  function checks to make sure that the window will fit 
  656.     on  to the physical screen and if not, will adjust the coordinates so  
  657.     that it will fit. 
  658.  
  659.     Returns:  A non-zero result if the move was successful.
  660.     Example:
  661.  
  662.     #include <pcwproto.h>
  663.  
  664.     void main(void) {
  665.  
  666.        WNDPTR *wnd;
  667.        int    lcv;
  668.  
  669.        wnd = wexplode(1,1,5,20,RED,LIGHTGRAY);
  670.        if (wnd == (WNDPTR *) 0) exit(3);
  671.        wtitle(wnd,TOP,MIDDLE, " Moving! ");
  672.        for (lcv = 1; lcv < 11; lcv++) {
  673.          wndmove(wnd,lcv*2,lcv*5);
  674.          rest(9);
  675.        }
  676.        wnd = wpop(wnd);
  677.     }
  678.  
  679.  
  680.                                  w_chg_attr()
  681.  
  682.     #include <pcwproto.h>
  683.     int  w_chg_attr(WNDPTR *wnd,int row,int col,int fclr,int bclr,int count);
  684.  
  685.     Description:    The  w_chg_attr()   function will  change  the  color 
  686.     attributes  starting  at  row and col coordinates  INSIDE  THE WINDOW  
  687.     addressed   by WNDPTR and repeated count times.    This  function  is 
  688.     useful  for   menus that  use  a color bar to indicate  a  selection.   
  689.     If   the   change   of attributes  attempts  to move outside  of  the 
  690.     window the  function  is aborted and no change of attributes occurs. 
  691.  
  692.     Returns:   A non-zero value if the function was successful.
  693.  
  694.     Example:   See  the  menudemo  program:   The  menu  functions  make 
  695.     extensive use of w_chg_attr. 
  696.  
  697.     
  698.  
  699.                                   wscroll()
  700.  
  701.     #include <pcwproto.h>
  702.     int wscroll(WNDPTR *wnd, int action, int count);
  703.  
  704.     Description:    The  wscroll()   function  will  scroll  the  window 
  705.     referenced   by  the  WNDPTR  pointer  variable.    The  action  flag 
  706.     determines  if the entire area of the window is scrolled or just  the 
  707.     area inside of the borders.  Setting this parameter to 0 will  scroll 
  708.     the entire area of the window (this includes the borders).    Setting 
  709.     it  to  a non-zero value will scroll the area inside of the  borders.  
  710.     The count parameter will specify the number of rows to scroll as well 
  711.     as the direction to scroll.   When the count parameter is a  positive 
  712.     value  the scrolling will be down,  and when the count is a  negative 
  713.     value the scrolling will be up.  Again,   if the window is overlapped 
  714.     by any other window it will be promoted to the top. 
  715.  
  716.     Returns: A non-zero value if successful.
  717.  
  718.     Example:
  719.  
  720.     #include <stdio.h>
  721.     #include <pcwproto.h>
  722.  
  723.     void main(void) {
  724.       WNDPTR *wnd;
  725.  
  726.       wnd = wpush(6,10,18,70);      /* Save area on screen */
  727.       set_wnd_attr(wnd,RED,RED);    /* Set window colors */
  728.       while(!kbhit()) {
  729.          wscroll(wnd,0,3);          /* Scroll wnd down 3 lines */
  730.          wscroll(wnd,0,-3);         /* Scroll wnd up 3 lines */
  731.       } getch(); wnd = wpop(wnd);   /* Clear keyboard & remove wnd */
  732.     }
  733.  
  734.  
  735.                                w_block_write()
  736.  
  737.     #include <pcwproto.h>
  738.     int w_block_write(WNDPTR *wnd, int row, int col, char *block[]);
  739.  
  740.     Description:    The w_block_write()  function will write an array  of 
  741.     strings to the window referenced by WNDPTR *,  starting at the row  & 
  742.     column   specified  and  continuing on a new line  until  the  entire  
  743.     array  of  strings  has been written to the window or until  no  more 
  744.     lines   can  be  written into the window,   whichever  occurs  first.   
  745.     NOTE  the array of  strings must be NULL terminated.    The color  of 
  746.     the   text  will be determined by the color used when the window  was 
  747.     defined or set by the set_wnd_attr() function. 
  748.  
  749.     Returns:   A non-zero value if completed successfully.  If the entire 
  750.     array of strings could not be written to the window then a zero value 
  751.     will be returned. 
  752.  
  753.     Example:
  754.  
  755.     #include <stdio.h>
  756.     #include <pcwproto.h>
  757.  
  758.     void main(void) {
  759.  
  760.        static char *msgs[] = {
  761.           "Description:  w_block_write will write an  array  of  strings",
  762.           "into your window in one fell swoop.  This is  very convenient",
  763.           "and keeps you from having to set up loops to do this function",
  764.           NULL 
  765.        };
  766.        WNDPTR *wnd;
  767.        bordercolor(BLUE,LIGHTGRAY);
  768.        titlecolor(BLACK,LIGHTGRAY);
  769.        wnd = wframe(6,5,12,75,RED,LIGHTGRAY);
  770.        wtitle(wnd, TOP,MIDDLE," w_block_write ");
  771.        w_block_write(wnd,2,CENTER,msgs);
  772.        keywait(10); wnd = wpop(wnd);
  773.     } 
  774.  
  775.  
  776.                                   pcwinit()
  777.  
  778.     #include <pcwproto.h> void pcwinit(int  action); 
  779.  
  780.     Description:   The  pcwinit()   function initializes the  PC  Windows 
  781.     library functions. It is not necessary to call this function in every 
  782.     program  because  almost all (but not all)  of the functions  in  the 
  783.     library  check  to see if the library has been initialized  and  call 
  784.     pcwinit()  if it has not.  The integer parameter, action,  is used to 
  785.     notify PCW whether an automatic exit is desired.  The default (if you 
  786.     let PCW initialize for you) is to set an automatic exit to remove all 
  787.     windows  from  the screen.   To disable this feature you must  invoke 
  788.     pcwinit()   with an action of NOEXIT before you invoke any other  PCW 
  789.     function. To invoke pcwinit()  and install the automatic exit use the 
  790.     manifest constant AUTOEXIT. 
  791.  
  792.     Returns: Nothing
  793.     Example:
  794.  
  795.     #include <pcwproto.h>                 
  796.     void main(void) {
  797.        pcwinit(NOEXIT);        /* or AUTOEXIT */
  798.        vcls();
  799.        qputs(10,1,RED,BLACK,"The library is initialized!");
  800.     }
  801.  
  802.  
  803.                                   clr_wnd()
  804.  
  805.     #include <pcwproto.h>
  806.     int clr_wnd(WNDPTR *wnd, int action);
  807.  
  808.     Description:   The clr_wnd()   function will clear the contents of  a 
  809.     window    specified   with   the  WNDPTR  variable.     The    action  
  810.     parameter specifies  whether   the area to be  cleared  includes  the 
  811.     border of the window or not. If this parameter is non-zero  only  the 
  812.     area  inside  of the borders will be cleared,  otherwise the  borders 
  813.     will be cleared too. 
  814.  
  815.     Returns: Non-zero value if successful.
  816.  
  817.     Example:
  818.  
  819.     #include <pcwproto.h>
  820.     void main(void) {
  821.        WNDPTR *wnd1, *wnd2;
  822.        
  823.        bordercolor(BLUE,LIGHTGRAY);
  824.        wnd1 = wframe(1,1,10,40,BLACK,BROWN);
  825.        wnd2 = wframe(5,15,15,55,BLACK,LIGHTGRAY);
  826.        keywait(5);
  827.        clr_wnd(wnd1,0); wputs(wnd1,1,1,"The borders were cleared");
  828.        keywait(10);
  829.        clr_wnd(wnd2,1); wputs(wnd2,1,1,"Borders are not cleared");
  830.        keywait(10);
  831.        wnd1=wpop(wnd1);swait(3);wnd2= wpop(wnd2);
  832.     }
  833.     
  834.     
  835.                                 set_wnd_attr()
  836.  
  837.     #include <pcwproto.h>
  838.     void set_wnd_attr(WNDPTR *wnd, int fcolor, int bcolor);
  839.  
  840.     Description:   The set_wnd_attr()  function can be used to change the 
  841.     color  attributes  of  a  window.   When  a  window  is  created  the 
  842.     attributes  of  that  window are stored and used  on  all  subsequent 
  843.     accesses to the window.  set_wnd_attr() allows these color attributes 
  844.     to  be changed after the window has been created so  that  subsequent 
  845.     accesses to the window will now use the new color attributes. 
  846.  
  847.     Returns: Nothing
  848.  
  849.     Example:
  850.  
  851.     #include <stdio.h>
  852.     #include <pcwproto.h>
  853.  
  854.     void main(void) {
  855.  
  856.        WNDPTR *wnd;
  857.        
  858.        wnd = wpush(6,20, 18, 60);
  859.        wputs(wnd, 1, CENTER, "Lightgray on Black");
  860.        keywait(3);
  861.        set_wnd_attr(wnd,WHITE,RED);
  862.        wputs(wnd, 2, CENTER, "White on Red");
  863.        keywait(3); clr_wnd(wnd,0); keywait(3);
  864.     }
  865.     
  866.                             Quick Screen Routines
  867.  
  868.  
  869.                                   qputchar()
  870.  
  871.     #include <pcwproto.h>
  872.     int qputchar(int row,int col,int fclr,int bclr,char ch);
  873.  
  874.     Description: The qputchar() function writes the character (ch) to the 
  875.     video  screen  at  the  specified row and  column  (col)   using  the 
  876.     specified foreground color (fclr)  and the specified background color 
  877.     (bclr). 
  878.  
  879.     Returns: Non-zero value if successful.
  880.  
  881.     Example:
  882.  
  883.     #include <pcwproto.h>
  884.     void main(void) {
  885.        int rw, cl, cnt = 0;
  886.        vcls();
  887.        for (rw = 0; rw < 16; rw++) {
  888.           for (cl = 0; cl < 16; cl++) {
  889.              qputchar(5+rw,32+cl,BLUE,LIGHTGRAY,cnt++);
  890.           }
  891.        }
  892.     }
  893.     
  894.  
  895.                                    qfill()
  896.  
  897.     #include <pcwproto.h>
  898.     int qfill(int ur,int uc,in lr,int lc,int fclr,int bclr,int chr);
  899.  
  900.     Description:  The qfill()  function will fill a specified rectangular 
  901.     area on the video screen with the specified characters (chr)  in  the 
  902.     specified colors  (fclr  &  bclr).     The area on the screen to   be  
  903.     filled   is  demarcated by the upper row and upper column (ur  &  uc)  
  904.     and lower row and lower column (lr & lc). 
  905.  
  906.     Returns:  Non-zero value if successful.
  907.  
  908.     Example:
  909.  
  910.     #include <pcwproto.h>
  911.     void main(void) {
  912.       WNDPTR *wnd;
  913.  
  914.       wnd = wpush(6,10,18,70);
  915.       qfill(6,10,18,70,RED,RED); keywait(10);
  916.       wnd = wpop(wnd);
  917.     }
  918.     
  919.  
  920.                                     qbox()
  921.  
  922.     #include <pcwproto.h>
  923.     int qbox(int urow, int ucol, int lrow, int lcol);
  924.  
  925.     Description:  The qbox() function will draw a box on the screen.  The 
  926.     characters  used to draw the box are specified with  the  setborder() 
  927.     function.   The color of the box is specified with the  bordercolor() 
  928.     function. 
  929.  
  930.     Returns: Nothing
  931.  
  932.     Example:
  933.     #include <pcwproto.h>
  934.     void main(void) {
  935.       int ur, uc, lr, lc;
  936.  
  937.       vcls();
  938.       setborder(SINGLESIDES);
  939.       bordercolor(CYAN,BLACK);
  940.       for (ur=1,uc=1,lr=25,lc=80;ur < lr && uc < lc; ur += 1, uc += 4)
  941.           qbox(ur,uc,lr,lc);
  942.     }
  943.  
  944.  
  945.                                     qvchar()
  946.  
  947.     #include <pcwproto.h>
  948.     int qvchar(int row,int col,int fclr,int bclr,char chr,int count);
  949.  
  950.     Description:   The qvchar()  function repeats the specified character 
  951.     (chr)   count  times  vertically on the screen originating at  row  & 
  952.     column (col) using the colors specified by fclr and bclr. 
  953.  
  954.     Returns: Non-zero value if successful.
  955.  
  956.     Example:
  957.     #include <pcwproto.h>
  958.     void main(void) {
  959.        int row, col, chr;
  960.  
  961.        vcls();
  962.        for (row=1,col=1,chr=33; row < 25; row++, col+=3,chr++)
  963.           qvchar(row,col,7,0,chr,25-row);
  964.     }
  965.     
  966.    
  967.  
  968.                                    qhchar()
  969.                                             
  970.     #include <pcwproto.h>
  971.     int qhchar(int row,int col,int fclr,int blcr,char chr,int count);
  972.  
  973.     Description:   The qhchar()  function repeats the specified character 
  974.     (chr)  count times  horizontally on the screen originating at row and 
  975.     column (col) using the color attributes specified by fclr and bclr. 
  976.  
  977.     Returns: Non-zero value if successful.
  978.  
  979.     Example:
  980.     #include <pcwproto.h>
  981.     void main(void) {
  982.       int row, col, chr;
  983.       vcls();
  984.       for (row=1,col=1,chr=65; row < 25;row++,col+=3,chr++)
  985.           qhchar(row,col,4,0,chr,80-col);
  986.     }
  987.     
  988.  
  989.                                    qputs()
  990.  
  991.     #include <pcwproto.h>
  992.     int qputs(int row,int col,int fclr,int bclr,char *string);
  993.  
  994.     Description:    The  qputs()  function writes  the  character  string 
  995.     (*string)  to the video display at the coordinates (row & col) in the 
  996.     specified  color  attributes (fclr & bclr).   No character  filtering 
  997.     takes place and no line-feed character is inserted at the end of  the 
  998.     string. 
  999.  
  1000.     Returns:  A non-zero value if successful.
  1001.  
  1002.     Example:
  1003.     #include <pcwproto.h>
  1004.     void main(void) {
  1005.        char *string = "Hello World...PCW is here!";
  1006.        vcls();
  1007.        qputs(12,CENTER,WHITE,BLACK+BLINK,string);
  1008.     }
  1009.     
  1010.        
  1011.                                     qvputs()
  1012.  
  1013.     #include <pcwproto.h>
  1014.     int qvputs(int row, int col, int fclr, int bclr, char *string);
  1015.  
  1016.     Description:    The  qvputs()  function writes the  character  string 
  1017.     (*string) to video display vertically originating from row and column 
  1018.     (col) with the specified color attributes (fclr & bclr). 
  1019.  
  1020.     Returns:  A non-zero value if successful.
  1021.  
  1022.     Example:
  1023.  
  1024.     #include <pcwproto.h>
  1025.     void main(void) {
  1026.        int  lcv,mxr,mxc;
  1027.        if (!chk_video_state(&mxr,&mxc)) exit(3);
  1028.        for (lcv = 1; lcv <= mxc; lcv++) 
  1029.           qvputs(1,lcv,15,0,"Hello World PCW Here!");
  1030.     }
  1031.     
  1032.  
  1033.                                 q_block_write()
  1034.     
  1035.     #include <pcwproto.h>
  1036.     int q_block_write(int row,int col,int fclr,int blcr,char *block[]);
  1037.  
  1038.     Description:   The q_block_write()   function will accept an array of 
  1039.     pointers  to  character strings (*block[])  and write  the  character 
  1040.     strings to the video display in one fell swoop.   The first character 
  1041.     string  is written at row and col and the row is  incremented  before 
  1042.     each string is written to the display.   The color is specified  with 
  1043.     the fclr and bclr variables.    The array of pointers should be  NULL 
  1044.     terminated. 
  1045.  
  1046.     Returns:  A non-zero value if successful.
  1047.  
  1048.     Example:
  1049.  
  1050.     #include <stdio.h>
  1051.     #include <pcwproto.h>
  1052.  
  1053.     static char *block[] = {
  1054.        "q_block_write() make writing arrays of character",
  1055.        "strings a breeze because you do not have to  set",
  1056.        "up loops to do it yourself",
  1057.        NULL
  1058.     };
  1059.     void main(void) {
  1060.        vcls();
  1061.        q_block_write(10,25,4,0,block);
  1062.     }
  1063.     
  1064.  
  1065.                                   qprintf()
  1066.  
  1067.     #include <pcwproto.h>
  1068.     int qprintf(int row,int col,int fclr,int bclr,char *format,...);
  1069.  
  1070.     Description:  The qprintf() function writes a formatted string to the 
  1071.     video  display much the same as the standard printf()  function does, 
  1072.     however,   no character filtering takes place.   This  means  newline 
  1073.     characters  are not interpreted and are written to the video display. 
  1074.     The string is written at the row and column (col) specified using the 
  1075.     color attributes specified by the fclr and bclr variables. 
  1076.     
  1077.     Returns:  A non-zero value if successful completed.
  1078.     
  1079.     Example:
  1080.     
  1081.     #include <pcwproto.h>
  1082.     void main(void) {
  1083.       char *format = "qprintf is very quick and fast.  Row = %0d";
  1084.       int row;
  1085.       for (row=1,row < 26; row++)
  1086.         qprintf(row,CENTER,BLUE,LIGHTGRAY,format,row);
  1087.     }
  1088.     
  1089.  
  1090.                                    scroll()
  1091.  
  1092.     #include <pcwproto.h>
  1093.     int scroll(int ur,int uc,int lr,int lc,int fclr,int bclr,int count);
  1094.  
  1095.     Description:  The scroll()  function will scroll the rectangular area 
  1096.     of  the  screen demarcated by the ur uc (upper row &  col-upper  left 
  1097.     corner)   and  the  lr & lc (lower row & col -  lower  right  corner) 
  1098.     variables.    The scroll function will not cause flicker as does  the 
  1099.     BIOS  scrolling  on some video adapters.   As the demarcated area  is 
  1100.     scrolled the color attributes fclr and bclr specify the color of  the 
  1101.     blanked  lines  added  to the scroll  region.    The  count  variable 
  1102.     determines  the  number of lines scrolled.    Furthermore,  the  count 
  1103.     variable determines the direction.  If the count variable is positive 
  1104.     the  scroll  region is scrolled downward and if negative  the  scroll 
  1105.     region is scrolled up. 
  1106.     
  1107.     Returns:  A non-zero value if completed successfully.
  1108.     
  1109.     Example:
  1110.     
  1111.     #include <pcwproto.h>
  1112.     void main(void) {
  1113.        WNDPTR wnd;
  1114.     
  1115.        wnd = wpush(6,10,18,70);
  1116.        while(!keypressed()) {
  1117.          scroll(6,10,18,70,RED,RED,   3);/* Scroll region down 3 */
  1118.          scroll(6,10,18,70,BLUE,BLUE,-3);/* Scroll region up 3 lines */ 
  1119.        } keybrd_flush();
  1120.        wnd = wpop(wnd);
  1121.     }
  1122.     
  1123.  
  1124.                                   getattr()
  1125.      
  1126.     #include <pcwproto.h>
  1127.     int getattr(int row, int col);
  1128.  
  1129.     Description:  The getattr() function returns the color attribute at 
  1130.     the specified row and column.
  1131.  
  1132.     Returns:  The color attribute at row and column.  Returns -1 if 
  1133.     unsuccessful.
  1134.  
  1135.  
  1136.                                    getchr()
  1137.  
  1138.     #include <pcwproto.h>
  1139.     int getchr(int row, int col);
  1140.  
  1141.     Description:  The getchr() function returns the character at the 
  1142.     specified row and column.  Returns a -1 if unsuccessful.
  1143.     
  1144.  
  1145.                            Bios Dependant Functions
  1146.  
  1147.  
  1148.                               get_cursor_size()
  1149.  
  1150.     #include <pcwproto.h>
  1151.     void get_cursor_size(int *tline, int *bline);
  1152.  
  1153.     Description: The get_cursor_size() function returns the beginning and 
  1154.     ending  scan lines of the text cursor in the integer pointers.    You 
  1155.     should use this function at the beginning of your program if you  are 
  1156.     planning  to turn the cursor off at any time during the execution  of 
  1157.     your program. 
  1158.  
  1159.     Returns: Nothing.                
  1160.  
  1161.     Example:
  1162.     #include <pcwproto.h>
  1163.     void main(void) {
  1164.        int tl, bl;
  1165.        vcls(); get_cursor_size(&tl, &bl);
  1166.        set_cursor_size(0,0); keywait(10);
  1167.        set_cursor_size(tl,bl);
  1168.     }
  1169.  
  1170.                               set_cursor_size()
  1171.  
  1172.     #include <pcwproto.h>
  1173.     void set_cursor_size(int tline, bline);
  1174.  
  1175.     Description:   The set_cursor_size()  function will set the beginning 
  1176.     and ending scan lines of the text cursor.   This function is used  in 
  1177.     conjunction  with get_cursor_size()   function to turn the cursor  on 
  1178.     and  off   frequently.     If  both  scan  line  values  passed    to   
  1179.     the set_cursor_size function are zero the cursor will be turned off. 
  1180.  
  1181.     Returns:  Nothing
  1182.  
  1183.     Example:  See above example.
  1184.     
  1185.  
  1186.                                get_cursor_pos()
  1187.  
  1188.     #include <pcwproto.h>
  1189.     void get_cursor_pos(int *row, int *col);
  1190.  
  1191.     Description:  The get_cursor_pos() returns the position of the text 
  1192.     cursor on the current video page in the two integer pointers.
  1193.  
  1194.     Returns:  Nothing
  1195.  
  1196.     Example:
  1197.       
  1198.     #include <pcwproto.h>
  1199.     void main(void) {
  1200.        int row, col
  1201.  
  1202.        set_cursor_pos(12,40);
  1203.        get_cursor_pos(&row, &col);
  1204.        qprintf(12,CENTER,RED,0,"Cursor Row = %d Cursor Col = %d",row,col);
  1205.     }
  1206.  
  1207.                                set_cursor_pos()
  1208.  
  1209.     #include <pcwproto.h>
  1210.     void set_cursor_pos(int row, int col);
  1211.  
  1212.     Description:   The set_cursor_pos() function sets the cursor position 
  1213.     to the the row and column specified in the argument list. 
  1214.  
  1215.     Returns:  Nothing.
  1216.  
  1217.     Example:  See above expample.
  1218.     
  1219.  
  1220.                                  switchpage()
  1221.  
  1222.     #include <pcwproto.h>
  1223.     void switchpage(int videopage);
  1224.  
  1225.     Description:  The switchpage() function will switch the current video 
  1226.     page to the one specified by the videopage parameter.   With adapters 
  1227.     such as the CGA,  EGA,  and VGA there are more than one video page in 
  1228.     which to display video output,  however only one video page at a time 
  1229.     may be displayed.   It is possible,  therefore,  to build a screen in 
  1230.     the  background on a video page not displayed and then switch to  it. 
  1231.     The  number of video pages depend on the video adapter you are  using 
  1232.     and the video mode you are using.  See also the setpage() function. 
  1233.     
  1234.     Returns:  Nothing
  1235.     
  1236.     Example:
  1237.  
  1238.     #include <pcwproto.h>
  1239.     void main(void) {
  1240.        int i;
  1241.        pcwinit();
  1242.        setpage(1);
  1243.        for (i=1;i<25;i++) qputs(i,CENTER,RED,BLACK,"Hello World!");
  1244.        keywait(5);
  1245.        switchpage(1); keywait(5);
  1246.        switchpage(0);
  1247.     }
  1248.     
  1249.  
  1250.                                     vcls()
  1251.  
  1252.     #include <pcwproto.h>
  1253.     void vcls(void);
  1254.  
  1255.     Description:    The vcls()  function will clear the video display and 
  1256.     set the color attributes to lightgray on black much like the DOS  cls 
  1257.     command.    However,   unlike the DOS cls command if your display  is 
  1258.     using the EGA 43 line mode or the VGA 50 line mode all 25, 43,  or 50 
  1259.     lines will be cleared. 
  1260.  
  1261.     Returns:  Nothing.
  1262.  
  1263.  
  1264.                                   vgetmode()
  1265.  
  1266.     #include <pcwproto.h>
  1267.     void vgetmode(int *cols, int *mode, int *activepage);
  1268.  
  1269.     Description:   The vgetmode function is used to return the number of 
  1270.     columns,  the video mode,  and the active video page of the  current 
  1271.     display. 
  1272.  
  1273.     Returns:  Nothing.
  1274.  
  1275.     Example:
  1276.  
  1277.     #include <stdio.h>
  1278.     #include <pcwproto.h>
  1279.     void main(void) {
  1280.      int cols,mode,ap;
  1281.      vgetmode(&cols,&mode,&ap);
  1282.      printf("The mode is %d, the number of columns is %d, acivepage is %d",
  1283.              mode, cols, ap);
  1284.     }
  1285.     
  1286.     
  1287.                                   vgetattr()
  1288.  
  1289.     #include <pcwproto.h>
  1290.     int vgetattr(void);
  1291.  
  1292.     Description:  The vgetattr()  function returns the color attribute on 
  1293.     the video display at the cursor location. 
  1294.  
  1295.     Returns:  The color attribute.
  1296.  
  1297.     Example:
  1298.  
  1299.     #include <pcwproto.h>
  1300.     void main(void) {
  1301.        int attr, chr;
  1302.        set_cursor_pos(1,1);
  1303.        attr = vgetattr();
  1304.        chr  = vgetchr();
  1305.        printf("Attribute = %x, Character = %c",attr,chr);
  1306.     }
  1307.  
  1308.  
  1309.                                   vgetchr()
  1310.  
  1311.     #include <pcwproto.h>
  1312.     int vgetattr(void);
  1313.  
  1314.     Description:   The vgetchr()  function returns the character from the 
  1315.     video display at the current cursor position. 
  1316.  
  1317.     Example:  See above example.
  1318.     
  1319.                                   vsetmode()
  1320.  
  1321.     #include <pcwproto.h>
  1322.     void vsetmode(int mode);
  1323.  
  1324.     Description:   The vsetmode() function will set the video mode of the 
  1325.     EGA/VGA/CGA/MDA adapter.   For color adapters the video mode used for 
  1326.     text   processing   is mode 3,   while for monochrome  monitors   the  
  1327.     most  frequently   used mode is mode 7.    When the mode is  set  the 
  1328.     screen is cleared and the contents are lost. 
  1329.  
  1330.     Example:
  1331.  
  1332.     #include <pcwproto.h>
  1333.     void main(void) {
  1334.  
  1335.        pcwinit(NOEXIT);
  1336.        (_monitor == COLOR) ? vsetmode(3) : vsetmode(7);
  1337.     }
  1338.     
  1339.                              set_vga_scan_lines()
  1340.  
  1341.     #include <pcwproto.h>
  1342.     void set_vga_scan_lines(int arg);
  1343.  
  1344.     Description:  Sets the number of scan lines to be used on the display 
  1345.     of  a  VGA unit.   The value for arg can be one of  three:    CGA200, 
  1346.     EGA350,  VGA400.  Using CGA200  will cause the VGA adapter to use 200 
  1347.     scan  lines for its display which will look just like a CGA  display.  
  1348.     Using EGA350 will cause 350 scan lines to be used which is equivelant 
  1349.     to  an  EGA  display and VGA400  will use 400   scan  lines  for  VGA 
  1350.     resolution (which is what you paid for).
  1351.     
  1352.     Example:
  1353.     
  1354.     #include <stdlib.h>
  1355.     #include <pcwproto.h>
  1356.     void main(void) {
  1357.     
  1358.       int lcv;
  1359.  
  1360.       for (lcv = 0; lcv <= EGA400; lcv++) {
  1361.           set_vga_scan_lines(lcv);
  1362.           system("dir");
  1363.           keywait(10);
  1364.       }
  1365.     }
  1366.      
  1367.  
  1368.                                    fload()
  1369.  
  1370.     #include <pcwproto.h>
  1371.     void fload(int block, int font);
  1372.  
  1373.     Description:    The  fload()   function will load one  of  the  three 
  1374.     standard  fonts on the EGA/VGA and reprogram the video controller and 
  1375.     will ensure the cursor works correctly.  On all adapters an 8x8  font 
  1376.     can be loaded to create 43 text line mode on the EGA and 50 text line 
  1377.     mode on the VGA.  An 8x14 font can be loaded on the EGA/VGA,  however 
  1378.     this  will cause 28  text line mode on the VGA unless the  number  of 
  1379.     scan  lines is set to 350.   If a VGA is active an 8x16  font can  be 
  1380.     loaded (this is the normal font for VGA). 
  1381.     The value used for the 'block'  parameter can be 0-3 with 0 being the 
  1382.     most used.  The legitimate values for 'font' are 8, 14, and 16. 
  1383.  
  1384.     Example:  (Assumes an EGA/VGA)
  1385.  
  1386.     #include <stdlib.h>
  1387.     #include <pcwproto.h>
  1388.  
  1389.     void main(void) {
  1390.  
  1391.        system("dir");
  1392.        fload(0,8);
  1393.        keywait(10);
  1394.        (_adaptor == EGA) ? fload(0,14) : fload(0,16);
  1395.     }
  1396.  
  1397.  
  1398.                              download_rom_font()
  1399.  
  1400.     #include <pcwproto.h>
  1401.     int download_rom_font(int font, char *buffer);
  1402.  
  1403.     Description:     The  download_rom_font()   function  will  copy  the 
  1404.     specified font, either 8x14 or 8x16, from the EGA or VGA ROM into the 
  1405.     user  supplied buffer.   Use the manifest constant values EGA14   and 
  1406.     VGA16 for the font parameter.  The user supplied buffer must be large 
  1407.     enough to hold (16 * 256) bytes for the 8x16 font or (14 * 256) bytes 
  1408.     for the 8x14 font. 
  1409.  
  1410.     Returns:  The number of bytes per character are returned if the 
  1411.     function is successful, otherwise zero is returned.
  1412.  
  1413.     Example:  See example below.
  1414.  
  1415.  
  1416.                                load_user_font()
  1417.  
  1418.     #include <pcwproto.h>
  1419.     int load_user_font(int bpc,int blk,int nchrs,int fchr,char *buffer);
  1420.  
  1421.     Description:      The  load_user_font()  function is used to  load  a 
  1422.     user's   "soft font"    into the EGA/VGA registers.    The parameters 
  1423.     are explained as follows: 
  1424.         1. bpc - bytes per character, use either EGA14 or VGA16.
  1425.         2. blk - video block to load the font (usually 0).
  1426.         3. nchrs - number of characters in the font buffer.
  1427.         4. fchr - first character in font buffer
  1428.         5. *buffer - the font buffer (can be obtained by using 
  1429.            download_rom_font()).
  1430.  
  1431.     Following  the  load  of a user font, a video reset will  reload  the 
  1432.     default ROM font. 
  1433.  
  1434.     Returns:  A non-zero value is returned if the function is successful. 
  1435.     Example: 
  1436.  
  1437.     void main(void) {   /* make 'a' into 'b' and 'b' into 'c'.... */
  1438.  
  1439.        int i, j, k, x;
  1440.        static char ftable[16*256];
  1441.        
  1442.        pcwinit(NOEXIT);
  1443.        if (_adaptor > CGA) {
  1444.           k = (_adaptor == EGA) ? EGA14 : VGA16;
  1445.           if ((k = download_rom_font(k, ftable)) != 0) {
  1446.              for (i = 'a'; i <= 'z'; i++) {
  1447.                   j = i * k;
  1448.                   x = j + k;
  1449.                   while (j < x) {
  1450.                      ftable[j] = ftable[j + k];
  1451.                      j++;
  1452.                   }
  1453.              }
  1454.              load_user_font(k, 0, 256, 0, ftable);
  1455.           }
  1456.        }
  1457.        else puts("Must have an EGA or VGA to run this demo");
  1458.     }
  1459.     
  1460.  
  1461.                               get_ega_palette()
  1462.  
  1463.     #include <pcwproto.h>
  1464.     char *get_ega_palette(int mode);
  1465.  
  1466.     Description:  Makes an internal copy of the values in the EGA palette 
  1467.     regsisters  specified  by mode into an internal buffer and returns  a 
  1468.     pointer  to  the  buffer.   The size of the buffer is 17   bytes  and 
  1469.     represents  the  values  in the 16  EGA palette  registers  with  the 
  1470.     overscan  regsiter.    The values in this table may be  modified  and 
  1471.     reloaded  into  the palette registers  using  the  load_ega_palette() 
  1472.     function.    Together these functions allow you to use all 64  of the 
  1473.     available colors in text mode on the EGA/VGA. 
  1474.  
  1475.     Returns:  Pointer to internal register buffer, NULL if unsuccessful.
  1476.     Example:  See example below.
  1477.  
  1478.  
  1479.                                 set_palette()
  1480.  
  1481.     #include <pcwproto.h>
  1482.     void set_palette(int attribute_register, int color);
  1483.  
  1484.     Description:    Sets the attribute register in the internal  register 
  1485.     table to the specified color.  The attribute_register value must be 0 
  1486.     through 15  and the color can be 0 through 63.  This function  allows 
  1487.     you to set all 16  palette registers to desired colors in memory  and 
  1488.     use those colors with load_ega_palette(). 
  1489.  
  1490.                               load_ega_palette()
  1491.  
  1492.     #include <pcwproto.h>
  1493.     void load_ega_palette(void);
  1494.  
  1495.     Description:    Loads the internal attribute register table into  the 
  1496.     EGA/VGA palette registers causing any changes in color to immediately 
  1497.     take effect.
  1498.     
  1499.                               set_load_palette() 
  1500.  
  1501.     #include <pcwproto.h>
  1502.     void set_load_palette(int palette_register, int color);
  1503.  
  1504.     Description:    Changes the value in the internal attribute  register 
  1505.     table  to  the  specified  color  and  reloads  the  EGA/VGA  palette 
  1506.     registers immediately.   This is equivalent to calling  set_palette() 
  1507.     followed by a call to load_ega_palette(). 
  1508.  
  1509.     Example:
  1510.     #include <pcwproto.h>
  1511.     void main(void) {
  1512.  
  1513.        WNDPTR *wnd;
  1514.        int i;
  1515.        if (get_ega_palette(22) != (char *) 0) {
  1516.           bordercolor(RED,RED);
  1517.           wnd = wframe(6, 20, 18, 60, RED, RED);
  1518.           for (i = 0; i < 64; i++) {
  1519.               set_load_palette(RED, i);
  1520.               swait(1);
  1521.           }
  1522.        }
  1523.     } 
  1524.     
  1525.                                  set_int24()   
  1526.  
  1527.  
  1528.     #include <pcwproto.h>
  1529.     int set_int24(void);
  1530.  
  1531.     Description:  The set_int24() function will install a custom critical 
  1532.     interrupt  handler under the control of your program.   The  critical 
  1533.     interrupt handler will then be responsible for disk errors,   printer 
  1534.     time outs or any other device type error.   When an error occurs  the 
  1535.     critical  interrupt  handler will open a window in the current  video 
  1536.     page,  display a title with the error message, display a menu,  and a 
  1537.     few  words of encouragement,  and if the error was a disk  error,   a 
  1538.     message appears in the middle of the window identifying the offending 
  1539.     disk(ett) drive.  When a selection is made control returns to DOS and 
  1540.     then  back  to your program (hopefully),  or the program  is  aborted 
  1541.     depending on the user's choice.   In all cases the window is  removed 
  1542.     from  the screen and the hated message "Abort,  Retry or Ignore"   is 
  1543.     avoided. Upon return to DOS the interrupt vector will automatically 
  1544.     be reset by DOS.
  1545.  
  1546.     Returns:  Non-zero value if successful
  1547.     Example: 
  1548.  
  1549.     #include <stdio.h> 
  1550.     #include <pcwproto.h> 
  1551.  
  1552.     void main(void) {
  1553.  
  1554.        FILE *fp;
  1555.        char *filename = "a:dummy.txt";
  1556.  
  1557.        pcwinit(0);
  1558.        if (set_int24() ) {
  1559.           puts("Please open the door to drive A: ");
  1560.           puts("and press a key to continue");
  1561.           while(!keypressed()); keyin();
  1562.           fp = fopen(filename, "r");
  1563.           if (fp == NULL) puts("Could not open file");
  1564.        }
  1565.     }
  1566.     
  1567.  
  1568.  
  1569.                                   set_int29()
  1570.  
  1571.     The  set_int29()   function  captures the DOS  fast  output  interrupt, 
  1572.     interrupt 29h so that when DOS is writing characters out from  standard 
  1573.     output or standard error devices,  the output will be captured in a PCW 
  1574.     window.  
  1575.  
  1576.     The reset_int29() function will remove the hooks that set_int29()  used 
  1577.     to capture DOS fast output.   NOTE!!!! If you use set_int29()  anywhere 
  1578.     in a program you must call reset_int29()  before the program ends.   If 
  1579.     you do not most likely your PC will lock up. 
  1580.  
  1581.     NOTE:  the set_int29() function does not work at all when using Zortech 
  1582.     and  limps along when using Power C.   Using Turbo C and MSC there were 
  1583.     no  problems at all.   Furthermore,  the set_int29()  function does not 
  1584.     work at all under Power C when compiled in the small memory model. 
  1585.  
  1586.     Example:
  1587.  
  1588.     #include <stdio.h>
  1589.     #include <pcwproto.h>
  1590.  
  1591.     int main ( void ) {
  1592.  
  1593.        WNDPTR *wnd;
  1594.  
  1595.        wnd = wframe(3, 1, 22, 80, BLACK, LIGHTGRAY);
  1596.        set_int29();
  1597.        system("type pcw.doc");
  1598.        reset_int29();
  1599.        wnd = wpop( wnd );
  1600.        return 0;
  1601.     }
  1602.  
  1603.  
  1604.                                Mouse Functions
  1605.     
  1606.  
  1607.                                  init_mouse()
  1608.  
  1609.     #include <pcwproto.h>
  1610.     int init_mouse(void);
  1611.  
  1612.     Description:   The init_mouse()   function will initialize the  mouse 
  1613.     hardware and software driver and return a non-zero value if the mouse 
  1614.     driver & hardware are present.  A global variable, mpresent,  will be 
  1615.     set to a non-zero value if the mouse is present.   If you want to use 
  1616.     the  mouse in your program you should call init_mouse()  and  examine 
  1617.     the value of the mpresent variable whenever you wish to determine  if 
  1618.     the  mouse   is  present.  It  would  also be a  good   practice   to  
  1619.     call init_mouse  at the end of your program to reset the mouse driver  
  1620.     for the next program.  Calling init_mouse() a  second time will reset 
  1621.     the  mpresent   variable  to a FALSE value.     Calling  init_mouse()  
  1622.     always hides the mouse cursor. 
  1623.  
  1624.     Returns:  A non-zero value if the mouse is present.
  1625.  
  1626.     Example:  See the program MOUSDEMO.C for exhaustive examples.
  1627.     
  1628.     
  1629.                                 get_mpressed() 
  1630.  
  1631.     #include <pcwproto.h>
  1632.     int get_mpressed(int button);
  1633.  
  1634.     Description:  The get_mpressed() function returns the number of times 
  1635.     a   mouse   button   has  been  pressed  since  the  last   call   to 
  1636.     get_mpressed().  Use  the  manifest constants LEFTM,   and  RITEM  to 
  1637.     specify   which  button  you want to know about.    The range can  be 
  1638.     from  0  to 65535  and the Mouse driver will not check for  overflow.  
  1639.     Once  called  for a particular button the count for  that  button  is 
  1640.     cleared. 
  1641.  
  1642.     Example:  See MOUSDEMO.C for exhaustive examples.
  1643.     
  1644.  
  1645.                                get_mreleased()
  1646.  
  1647.     #include <pcwproto.h>
  1648.     int get_mreleased(int button);
  1649.  
  1650.     Description:   The get_mreleased()  function is the compliment of the 
  1651.     get_mpressed()   function in that it returns the number of times  the 
  1652.     Mouse  key specified by button has been released since the last  call 
  1653.     to  get_mreleased.    Use the manifest constants RITEM and  LEFTM  to 
  1654.     specify  the button that you want to know about.   The range  can  be 
  1655.     from 0 to 65535 and the driver does not check for overflow. 
  1656.  
  1657.     Example:  See MOUSDEMO.C for examples.
  1658.     
  1659.  
  1660.                                  show_mouse()
  1661.  
  1662.     #include <pcwproto.h>
  1663.     void show_mouse();
  1664.  
  1665.     Description:   The show_mouse()  function will turn on or  show  the 
  1666.     Mouse cursor.   Once you have initialized the Mouse with init_mouse() 
  1667.     you must use show_mouse()  to make the mouse cursor visible.   If you 
  1668.     have  defined a region for the Mouse with mframe()  the Mouse  cursor 
  1669.     will appear in the region.   Making subsequent calls to  show_mouse() 
  1670.     will have no effect. 
  1671.  
  1672.     Examples:  See MOUSDEMO.C and MENUDEMO.C 
  1673.     
  1674.  
  1675.                                  hide_mouse()
  1676.  
  1677.     #include <pcwproto.h>
  1678.     void hide_mouse();
  1679.     
  1680.     Description:   The hide_mouse()  function will hide the mouse cursor.  
  1681.     Hiding   the  Mouse is necessary when using windows or  quick  screen 
  1682.     writes  as  there  is no way to tell where the Mouse  is.    If  your 
  1683.     program  uses the Mouse you should test the presence of the Mouse  by 
  1684.     checking the value of the global variable,  mpresent,   and turn  off 
  1685.     the Mouse if the value is non-zero.  Subsequent calls to hide_mouse() 
  1686.     will have no effect. 
  1687.  
  1688.     Examples:  See MOUSDEMO.C, MENUDEMO.C, PDEMO.C, and LDEMO.C
  1689.     
  1690.  
  1691.                                   get_mpos()
  1692.  
  1693.     #include <pcwproto.h>
  1694.     void get_mpos(int *row, int *col, int *button_status);
  1695.  
  1696.     Description:     The  get_mpos()    function is  primarily   intended  
  1697.     to retrieve the position of the Mouse cursor, but it can also be used 
  1698.     to retrieve  the  button  status.    When called the  Mouse  position  
  1699.     is  returned    in  the row & col pointers and the button status   is  
  1700.     also  returned.   The values returned for Mouse position are  correct 
  1701.     for  any video mode.    The possible return values for  button_status 
  1702.     and  their meanings are as follows: 
  1703.  
  1704.          1 = Left Mouse Button pressed.
  1705.          2 = Right Mouse Button pressed.
  1706.          3 = Both Mouse Buttons pressed.
  1707.  
  1708.     Examples:  See MOUSDEMO.C
  1709.     
  1710.  
  1711.                                   set_mpos()
  1712.  
  1713.     #include <pcwproto.h>
  1714.     void set_mpos(int row, int col);
  1715.  
  1716.     Description:  The set_mpos() function sets the Mouse cursor position 
  1717.     on the video display.
  1718.     
  1719.  
  1720.                                  set_mtype()
  1721.  
  1722.     #include <pcwproto.h>
  1723.     void set_mtype(int ctype, int arg1, int arg2);
  1724.  
  1725.     Description:   The set_mtype()   function will set the  Mouse  cursor 
  1726.     type.   The two cursor types are the hardware cursor or the  software 
  1727.     text cursor (Mouse soft cursor).   If ctype is 0, set_mtype() selects 
  1728.     the  software text cursor and arg1  and arg2  must select screen  and 
  1729.     cursor  mask (SEE MOUSDEMO.C).   If ctype is equal to 1 the  hardware 
  1730.     cursor is used and arg1 and arg2 select the beginning and ending scan 
  1731.     lines  for the cursor much like that of set_cursor_size().   You  may 
  1732.     set  the  Mouse  cursor type then call show_mouse()  to  display  the 
  1733.     results. 
  1734.  
  1735.     Examples: See Mousdemo.C also.
  1736.  
  1737.     #include <pcwproto.h>
  1738.  
  1739.    void main(void) {
  1740.  
  1741.       int ctype=1,arg1=1,arg2=0x7;
  1742.       int tl, bl;
  1743.  
  1744.       /* Take over hardware cursor */
  1745.       /* See MOUSDEMO.C for examples of using soft cursor */
  1746.  
  1747.       init_mouse(); get_cursor_size(&tl,&bl);
  1748.       set_mtype(ctype,arg1,arg2); show_mouse();
  1749.       keywait(60);
  1750.       init_mouse();                        /* Reset Mouse */
  1751.       set_cursor_size(tl,bl);              /* Set cursor size back */
  1752.    }
  1753.  
  1754.                               save_mouse_state() 
  1755.  
  1756.     #include <pcwproto.h>
  1757.     char *save_mouse_state(void);
  1758.  
  1759.     Description:   Use the save_mouse_state()  function to save the state 
  1760.     of  the Mouse driver before spawning to another program that uses  or 
  1761.     may  use the Mouse also.   The save_mouse_state()  function returns a 
  1762.     pointer  to  a buffer where the mouse state  information   is   held.  
  1763.     Upon  returning  from  the child process you may make a call  to  the 
  1764.     restore_mouse_state() function using the pointer to the saved area. 
  1765.  
  1766.     Returns:  A pointer to the saved buffer.  NULL if memory could not be 
  1767.     allocated. 
  1768.  
  1769.                             restore_mouse_state() 
  1770.  
  1771.     #include <pcwproto.h>
  1772.     void restore_mouse_state(char *buffer);
  1773.  
  1774.     Description:  The restore_mouse_state()  function uses a pointer to a 
  1775.     buffer  allocated by the save_mouse_state()  function to restore  the 
  1776.     state  of the Mouse driver after returning from a child process or  a 
  1777.     system() function call.   The memory allocated for the buffer is then 
  1778.     deallocated and returned to the free pool.  Upon completion the Mouse 
  1779.     is as it was when the Mouse state was saved. 
  1780.  
  1781.     Returns:  Nothing.
  1782.     
  1783.                               Keyboard Functions
  1784.  
  1785.     With  this  release of PCW the keyboard functions have been  completely 
  1786.     re-written to more closely integrate keyboard events and mouse  events.  
  1787.     Furthermore,   support  for console redirection has been  added.    Any 
  1788.     program  using  any  of the PCW keyboard functions should  include  the 
  1789.     header file KEYS.H.  Also,  the return values from these functions have 
  1790.     been  changed  to better isolate the special keys such as the  function 
  1791.     keys and the arrow keys.   These return values are of type int and most 
  1792.     times  when  special keys are involved are not in the range  of  normal 
  1793.     ASCII characters.  This has caused problems with the functions declared 
  1794.     in CTYPE.H such as toupper(),  tolower(), isalpha(),  and so on.   Most 
  1795.     notably the functions (macros) in Microsoft C and Turbo C have problems 
  1796.     with  the return values from the keyboard functions because they use  a 
  1797.     table  driven  method  of validation of the characters,  and  when  the 
  1798.     integer value from the keyboard function are not in the range of normal 
  1799.     characters,   problems  arise.    To alleviate this  problem  a  macro, 
  1800.     ischar(),   is defined in PCWPROTO.H.   An example use of this macro is 
  1801.     provided: 
  1802.  
  1803.     if ( ischar(ch) ) ch = toupper(ch);
  1804.     return ( ischar(ch) ? isalpha(ch) : 0 );
  1805.  
  1806.  
  1807.                                  Keypressed()
  1808.  
  1809.     #include <keys.h>
  1810.     #include <pcwproto.h>
  1811.     int keypressed(void);
  1812.  
  1813.     The  keypressed()   function  was  originally used to  determine  if  a 
  1814.     character was waiting in the keyboard que, but now is used to determine 
  1815.     if one of several input events is true.   The keypressed() function can 
  1816.     be used to determine if console standard input has been redirector,  or 
  1817.     if a character is waiting in keyboard que buffer, or if a mouse key has 
  1818.     been pressed.  The return values from keypressed signify which event is 
  1819.     true: 
  1820.         0 = No Event.
  1821.         1 = Console Standard Input is Redirected.
  1822.         2 = Character is pending in keyboard que buffer.
  1823.         3 = A mouse key has been pressed.
  1824.     function c
  1825.  
  1826.                                   readkey()
  1827.  
  1828.     #include <pcwproto.h>
  1829.     int readkey(void);
  1830.  
  1831.     Description:    The readkey() function will (1)  return the most recent 
  1832.     mouse   key   that  was  pressed  (  LEFT_MOUSE_KEY,    RITE_MOUSE_KEY, 
  1833.     BOTH_MOUSE_KEY ),  (2)  return the character that from a file that  has 
  1834.     been redirected to standard input,  and (3)  return a pending character 
  1835.     from the keyboard que buffer.  If none of these events has occured when 
  1836.     keyin() is called, keyin() will wait until one does occur.   The Ctrl-C 
  1837.     interrupt has no effect on this function. 
  1838.     
  1839.                                    isxkeybd()
  1840.  
  1841.     #include <keys.h>
  1842.     #include <pcwproto.h>
  1843.     int isxkeybd(void);
  1844.  
  1845.     Description:  The isxkeybd() function determines if the BIOS supports 
  1846.     an  extended keyboard or not.   If the BIOS does support an  extended 
  1847.     keyboard  it does not mean that an extended keyboard is  attached  to 
  1848.     the computer,  but it would be reasonable to assume that one is.   If 
  1849.     the  BIOS supports the extended keyboard your program can make use of 
  1850.     the F11 & F12 keys with other PCW keyboard functions. 
  1851.  
  1852.                                   keywait()
  1853.  
  1854.     #include <keys.h>
  1855.     #include <pcwproto.h>
  1856.     int keywait(int seconds);
  1857.  
  1858.     Description:   The keywait()  function will delay program execution for 
  1859.     the   specified  number of seconds or until a key is pressed,  keyboard 
  1860.     or mouse.   keywait()   will return a -1   if time elapsed with no  key 
  1861.     pressed and will return the keyboard character when a key is pressed. 
  1862.  
  1863.                                    keyin()
  1864.     #include <keys.h>
  1865.     #include <pcwproto.h>
  1866.     int keyin(void);
  1867.  
  1868.     Description:     With  this  release of PCW keyin()  is  an  alias  for 
  1869.     readkey(). 
  1870.     
  1871.                                 keybrd_flush()
  1872.  
  1873.     #include <pcwproto.h>
  1874.     void keybrd_flush(void);
  1875.  
  1876.     Description:   The keybrd_flush()   function will flush the  keyboard 
  1877.     buffer  of  all  characters  entered since the  last  access  to  the 
  1878.     keyboard.   This  is   useful  if  you  do  not wish  users  of  your 
  1879.     programs  to  enter keystrokes ahead of your prompts. 
  1880.  
  1881.                                  get_chars() 
  1882.  
  1883.     #include <keys.h>
  1884.     #include <pcwproto.h> 
  1885.     int get_chars(int rw,int cl,int fclr,int bclr,int len,char *buffr);
  1886.     
  1887.     Description:    The get_chars()  function will accept buffered  input 
  1888.     from  the  keyboard  at  the  specified  row  and  column  using  the 
  1889.     foreground and background colors specified by fclr and  bclr.     The 
  1890.     maximum number of  characters  that  may  be entered are specified by  
  1891.     len   and   the  characters themselves are stored  in  *buffr.    The 
  1892.     get_chars()   function  supports  the  left  and  right  arrow  keys,  
  1893.     destructive backspacing, the home  and  end keys,   and inserting and 
  1894.     deleting  characters.     When get_chars()  detects an error the bell 
  1895.     will  be sounded. In addition if *buffr contains a string it will  be 
  1896.     displayed  at  row and column  when get_chars()  is  called  and  the 
  1897.     string may be edited. 
  1898.  
  1899.     Returns:   Returns zero when the enter key is struck and will  return 
  1900.     the Esc characters when the Esc key is pressed. 
  1901.     
  1902.  
  1903.                             ENVIRONMENT FUCNTIONS
  1904.  
  1905.  
  1906.     The  environment function in PCW are used mostly for internal purposes 
  1907.     of PCW,  however,  some of them could be useful to your programs when 
  1908.     used with PCW.  Therefore, I document them here. 
  1909.  
  1910.  
  1911.                                   getpage()
  1912.  
  1913.     #include <pcwproto.h>
  1914.     #int getpage(void);
  1915.  
  1916.     Description:   The getpage()  function returns the current video page 
  1917.     in  which PCW is  operating.   The IBM PC color video,  when in  text 
  1918.     mode,   can  operate on 4 to 16  video pages depending on  the  video 
  1919.     adapter in use and the text mode being used.  It is possible with PCW 
  1920.     to set a video page with the setpage()  function and write to a video 
  1921.     page  not  displayed  and  later display  it  with  the  switchpage() 
  1922.     function. 
  1923.  
  1924.                                 getpagesize()
  1925.  
  1926.     #include <pcwproto.h>
  1927.     int getpagesize(void);
  1928.  
  1929.     Description:    The getpagesize()  function returns current  size  of  
  1930.     a video memory page.  Normally this is 4096 (when using 25 X 80  text 
  1931.     mode),  but it could be different if your monitor is using the EGA 43 
  1932.     line mode or the VGA 50 line mode.  This function is used extensively 
  1933.     within PCW. 
  1934.  
  1935.                                   setpage()
  1936.  
  1937.     #include <pcwproto.h>
  1938.     int setpage(int page);
  1939.  
  1940.     Description:  The setpage() function is used to set the current video 
  1941.     page for  PCW to work in.   Normally the video page is set to zero by  
  1942.     the  BIOS  when the PC is booted up.    PCW initializes this value to  
  1943.     what  the  BIOS is using when your program begins execution.   It  is 
  1944.     possible  to   force   PCW  to use another  video  page  for   screen  
  1945.     writing   while displaying the current video page (screen writing  in 
  1946.     the background),  and  later  switch to the video page where all  the 
  1947.     writing  was   done.   This gives the appearance  of  instant  screen 
  1948.     writing.
  1949.     
  1950.  
  1951.                                  ispcwinit()
  1952.  
  1953.     #include <pcwproto.h>
  1954.     int ispcwinit(void);
  1955.  
  1956.     Description:    The  ispcwinit function is used internally by PCW  to 
  1957.     determine if the kernel code of PCW has been initialized.   When your 
  1958.     program  calls  one of PCW's functions a check is made to see if  the 
  1959.     kernal  code  was  initialized,   and,  if it has not,  the  call  to 
  1960.     initialize  PCW is made.   This keeps you from having to remember  to 
  1961.     initialize PCW at the beginning of each of your programs. 
  1962.  
  1963.                               chk_video_state()
  1964.  
  1965.     #include <pcwproto.h>
  1966.     int chk_video_state(int *max_rows, int *max_cols);
  1967.  
  1968.     Description:  The chk_video_state()  function is a very useful one in 
  1969.     that it will do the follow for you: 
  1970.  
  1971.          1.  Initialize PCW.
  1972.          2.  Return a value indicating whether or not you can use PCW 
  1973.              with the current video environment.
  1974.          3.  Returns the maximum number of rows and columns on the video 
  1975.              display.
  1976.  
  1977.     The  main purpose of chk_video_state()  is to determine  whether  the 
  1978.     video display  is in text mode or not.  If the display is in graphics 
  1979.     mode  PCW  will not,  and can not do its  job.  If  successful,   the 
  1980.     integer pointers,  max_rows & max_cols are returned with the  maximum 
  1981.     number  of rows and columns on the video display.   For example,   if 
  1982.     your  display  was   in 40   column mode this would be  reflected  in 
  1983.     *max_cols,  and if the  display  was  in EGA 43  line mode this would  
  1984.     be  reflected  in *max_rows. 
  1985.  
  1986.                                  getscrnseg()
  1987.  
  1988.     #include <pcwproto.h>
  1989.     unsigned getscrnseg(void);
  1990.  
  1991.     Description:   The getscrnseg() function will return the segment used 
  1992.     to address the video display memory.   If the display is a monochrome 
  1993.     the getscrnseg()  function will return the value (in hex) 0xB000  and 
  1994.     will return 0xB800  if a color monitor is in use.   getscrnseg()   is 
  1995.     used internally by PCW. 
  1996.     
  1997.  
  1998.                            MISCELLANEOUS FUNCTIONS
  1999.  
  2000.  
  2001.                                    _sound()
  2002.  
  2003.     #include <pcwproto.h>
  2004.     void _sound(unsigned frequency);
  2005.  
  2006.     Description:    The  _sound()  function will create a tone  with  the 
  2007.     specified frequency.  The tone will continue to sound until a call to 
  2008.     the _nosound() function is made. 
  2009.  
  2010.                                   _nosound()
  2011.  
  2012.     #include <pcwproto.h>
  2013.     void _nosound(void);
  2014.  
  2015.     Description:  The _nosound() function will discontinue the tone 
  2016.     generated by the _sound() function.  
  2017.  
  2018.                                     rest()
  2019.  
  2020.     #include <pcwproto.h>
  2021.     void rest(unsigned timer_ticks);
  2022.  
  2023.     Description:   The rest()  function will suspend the execution of the 
  2024.     program  for the specified number of timer_ticks.   Approximately  18 
  2025.     timer_ticks occur each second so calling rest with a value of 9  will 
  2026.     be roughly 1/2 a second. 
  2027.  
  2028.                                    swait()
  2029.  
  2030.     #include <pcwproto.h>
  2031.     void swait(unsigned seconds);
  2032.  
  2033.     Description:   The swait()   function will suspend  program execution 
  2034.     for  the specified number of seconds.   swait()  functions very  much 
  2035.     like  sleep()  in Turbo C and Power C and has been included so  there 
  2036.     will be a delay function for MSC as well. 
  2037.  
  2038.                                    _delay()
  2039.  
  2040.     #include <pcwproto.h>
  2041.     void _delay(unsigned milliseconds);
  2042.  
  2043.     Description:   The _delay()   function will suspend program execution 
  2044.     for  the specified number of milliseconds.   To gain this measure  of 
  2045.     accuracy _delay was written in assembler and programs the 8253  timer 
  2046.     chip on the motherboard of the PC.   Channel 2 of the 8253  was  used 
  2047.     for  the timing delay because channel 0 is used for the BIOS Time  of 
  2048.     Day  Count and channel 1 is used for memory refresh.   Channel  2  is 
  2049.     also  used  to  produce sounds on the PC (this is  how  the  _sound() 
  2050.     function  works).    Therefore,  using sound functions  and  _delay() 
  2051.     should be mutually exclusive. 
  2052.  
  2053.  
  2054.                                  titlecolor()
  2055.  
  2056.     #include <pcwproto.h>
  2057.     void titlecolor(int fcolor, int bcolor);
  2058.  
  2059.     Description:    The  titlecolor()  function is used to set the  title 
  2060.     colors  when  titling a window.   If you do not use the  titlecolor() 
  2061.     function  before titling a window the color used will be the  default 
  2062.     color of lightgray on black. 
  2063.  
  2064.                                 bordercolor()
  2065.  
  2066.     #include <pcwproto.h>
  2067.     void bordercolor(int fcolor, int bcolor);
  2068.  
  2069.     Description:   The bordercolor()   function is used to set the  color 
  2070.     attributes for window borders when using the wframe(),   qbox(),  and 
  2071.     wexplode()  functions.   If you do not use bordercolor()  to set  the 
  2072.     attributes the default of lightgray on black will be used. 
  2073.  
  2074.                                  setborder()
  2075.  
  2076.     #include <pcwproto.h>
  2077.     void setborder(int border_type);
  2078.  
  2079.     Description:   The setborder() function will set the border type used 
  2080.     in all subsequent calls to qbox(), wframe(), and wexplode().  Use the 
  2081.     manifest constants DOUBLEALL, SINGLEALL, SINGLESIDES, DOUBLESIDES, or 
  2082.     NOSIDES  to specify the type of border you want to use.   The default 
  2083.     border type is DOUBLEALL. 
  2084.  
  2085. 
  2086.